home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / perl5 / PPI / Statement.pm < prev    next >
Encoding:
Perl POD Document  |  2010-07-06  |  11.1 KB  |  388 lines
  1. package PPI::Statement;
  2.  
  3. =pod
  4.  
  5. =head1 NAME
  6.  
  7. PPI::Statement - The base class for Perl statements
  8.  
  9. =head1 INHERITANCE
  10.  
  11.   PPI::Statement
  12.   isa PPI::Node
  13.       isa PPI::Element
  14.  
  15. =head1 DESCRIPTION
  16.  
  17. PPI::Statement is the root class for all Perl statements. This includes (from
  18. L<perlsyn>) "Declarations", "Simple Statements" and "Compound Statements".
  19.  
  20. The class PPI::Statement itself represents a "Simple Statement" as defined
  21. in the L<perlsyn> manpage.
  22.  
  23. =head1 STATEMENT CLASSES
  24.  
  25. Please note that unless documented themselves, these classes are yet to be
  26. frozen/finalised. Names may change slightly or be added or removed.
  27.  
  28. =head2 L<PPI::Statement::Scheduled>
  29.  
  30. This covers all "scheduled" blocks, chunks of code that are executed separately
  31. from the main body of the code, at a particular time. This includes all
  32. C<BEGIN>, C<CHECK>, C<UNITCHECK>, C<INIT> and C<END> blocks.
  33.  
  34. =head2 L<PPI::Statement::Package>
  35.  
  36. A package declaration, as defined in L<perlfunc|perlfunc/package>.
  37.  
  38. =head2 L<PPI::Statement::Include>
  39.  
  40. A statement that loads or unloads another module.
  41.  
  42. This includes 'use', 'no', and 'require' statements.
  43.  
  44. =head2 L<PPI::Statement::Sub>
  45.  
  46. A named subroutine declaration, or forward declaration
  47.  
  48. =head2 L<PPI::Statement::Variable>
  49.  
  50. A variable declaration statement. This could be either a straight
  51. declaration or also be an expression.
  52.  
  53. This includes all 'my', 'state', 'local' and 'our' statements.
  54.  
  55. =head2 L<PPI::Statement::Compound>
  56.  
  57. This covers the whole family of 'compound' statements, as described in
  58. L<perlsyn|perlsyn>.
  59.  
  60. This includes all statements starting with 'if', 'unless', 'for', 'foreach'
  61. and 'while'. Note that this does NOT include 'do', as it is treated
  62. differently.
  63.  
  64. All compound statements have implicit ends. That is, they do not end with
  65. a ';' statement terminator.
  66.  
  67. =head2 L<PPI::Statement::Break>
  68.  
  69. A statement that breaks out of a structure.
  70.  
  71. This includes all of 'redo', 'next', 'last' and 'return' statements.
  72.  
  73. =head2 L<PPI::Statement::Given>
  74.  
  75. The kind of statement introduced in Perl 5.10 that starts with 'given'.  This
  76. has an implicit end.
  77.  
  78. =head2 L<PPI::Statement::When>
  79.  
  80. The kind of statement introduced in Perl 5.10 that starts with 'when' or
  81. 'default'.  This also has an implicit end.
  82.  
  83. =head2 L<PPI::Statement::Data>
  84.  
  85. A special statement which encompasses an entire C<__DATA__> block, including
  86. the initial C<'__DATA__'> token itself and the entire contents.
  87.  
  88. =head2 L<PPI::Statement::End>
  89.  
  90. A special statement which encompasses an entire __END__ block, including
  91. the initial '__END__' token itself and the entire contents, including any
  92. parsed PPI::Token::POD that may occur in it.
  93.  
  94. =head2 L<PPI::Statement::Expression>
  95.  
  96. L<PPI::Statement::Expression> is a little more speculative, and is intended
  97. to help represent the special rules relating to "expressions" such as in:
  98.  
  99.   # Several examples of expression statements
  100.   
  101.   # Boolean conditions
  102.   if ( expression ) { ... }
  103.   
  104.   # Lists, such as for arguments
  105.   Foo->bar( expression )
  106.  
  107. =head2 L<PPI::Statement::Null>
  108.  
  109. A null statement is a special case for where we encounter two consecutive
  110. statement terminators. ( ;; )
  111.  
  112. The second terminator is given an entire statement of its own, but one
  113. that serves no purpose. Hence a 'null' statement.
  114.  
  115. Theoretically, assuming a correct parsing of a perl file, all null statements
  116. are superfluous and should be able to be removed without damage to the file.
  117.  
  118. But don't do that, in case PPI has parsed something wrong.
  119.  
  120. =head2 L<PPI::Statement::UnmatchedBrace>
  121.  
  122. Because L<PPI> is intended for use when parsing incorrect or incomplete code,
  123. the problem arises of what to do with a stray closing brace.
  124.  
  125. Rather than die, it is allocated its own "unmatched brace" statement,
  126. which really means "unmatched closing brace". An unmatched open brace at the
  127. end of a file would become a structure with no contents and no closing brace.
  128.  
  129. If the document loaded is intended to be correct and valid, finding a
  130. L<PPI::Statement::UnmatchedBrace> in the PDOM is generally indicative of a
  131. misparse.
  132.  
  133. =head2 L<PPI::Statement::Unknown>
  134.  
  135. This is used temporarily mid-parsing to hold statements for which the lexer
  136. cannot yet determine what class it should be, usually because there are
  137. insufficient clues, or it might be more than one thing.
  138.  
  139. You should never encounter these in a fully parsed PDOM tree.
  140.  
  141. =head1 METHODS
  142.  
  143. C<PPI::Statement> itself has very few methods. Most of the time, you will be
  144. working with the more generic L<PPI::Element> or L<PPI::Node> methods, or one
  145. of the methods that are subclass-specific.
  146.  
  147. =cut
  148.  
  149. use strict;
  150. use Scalar::Util   ();
  151. use Params::Util   qw{_INSTANCE};
  152. use PPI::Node      ();
  153. use PPI::Exception ();
  154.  
  155. use vars qw{$VERSION @ISA *_PARENT};
  156. BEGIN {
  157.     $VERSION = '1.213';
  158.     @ISA     = 'PPI::Node';
  159.     *_PARENT = *PPI::Element::_PARENT;
  160. }
  161.  
  162. use PPI::Statement::Break          ();
  163. use PPI::Statement::Compound       ();
  164. use PPI::Statement::Data           ();
  165. use PPI::Statement::End            ();
  166. use PPI::Statement::Expression     ();
  167. use PPI::Statement::Include        ();
  168. use PPI::Statement::Null           ();
  169. use PPI::Statement::Package        ();
  170. use PPI::Statement::Scheduled      ();
  171. use PPI::Statement::Sub            ();
  172. use PPI::Statement::Given         ();
  173. use PPI::Statement::UnmatchedBrace ();
  174. use PPI::Statement::Unknown        ();
  175. use PPI::Statement::Variable       ();
  176. use PPI::Statement::When           ();
  177.  
  178. # "Normal" statements end at a statement terminator ;
  179. # Some are not, and need the more rigorous _continues to see
  180. # if we are at an implicit statement boundary.
  181. sub __LEXER__normal { 1 }
  182.  
  183.  
  184.  
  185.  
  186.  
  187. #####################################################################
  188. # Constructor
  189.  
  190. sub new {
  191.     my $class = shift;
  192.     if ( ref $class ) {
  193.         PPI::Exception->throw;
  194.     }
  195.  
  196.     # Create the object
  197.     my $self = bless { 
  198.         children => [],
  199.     }, $class;
  200.  
  201.     # If we have been passed what should be an initial token, add it
  202.     my $token = shift;
  203.     if ( _INSTANCE($token, 'PPI::Token') ) {
  204.         # Inlined $self->__add_element(shift);
  205.         Scalar::Util::weaken(
  206.             $_PARENT{Scalar::Util::refaddr $token} = $self
  207.         );
  208.         push @{$self->{children}}, $token;
  209.     }
  210.  
  211.     $self;
  212. }
  213.  
  214. =pod
  215.  
  216. =head2 label
  217.  
  218. One factor common to most statements is their ability to be labeled.
  219.  
  220. The C<label> method returns the label for a statement, if one has been
  221. defined, but without the trailing colon. Take the following example
  222.  
  223.   MYLABEL: while ( 1 .. 10 ) { last MYLABEL if $_ > 5 }
  224.  
  225. For the above statement, the C<label> method would return 'MYLABEL'.
  226.  
  227. Returns false if the statement does not have a label.
  228.  
  229. =cut
  230.  
  231. sub label {
  232.     my $first = shift->schild(1) or return '';
  233.     $first->isa('PPI::Token::Label')
  234.         ? substr($first, 0, length($first) - 1)
  235.         : '';
  236. }
  237.  
  238. =pod
  239.  
  240. =head2 specialized
  241.  
  242. Answer whether this is a plain statement or one that has more
  243. significance.
  244.  
  245. Returns true if the statement is a subclass of this one, false
  246. otherwise.
  247.  
  248. =begin testing specialized 22
  249.  
  250. my $Document = PPI::Document->new(\<<'END_PERL');
  251. package Foo;
  252. use strict;
  253. ;
  254. while (1) { last; }
  255. BEGIN { }
  256. sub foo { }
  257. state $x;
  258. $x = 5;
  259. END_PERL
  260.  
  261. isa_ok( $Document, 'PPI::Document' );
  262.  
  263. my $statements = $Document->find('Statement');
  264. is( scalar @{$statements}, 10, 'Found the 10 test statements' );
  265.  
  266. isa_ok( $statements->[0], 'PPI::Statement::Package',    'Statement 1: isa Package'            );
  267. ok( $statements->[0]->specialized,                      'Statement 1: is specialized'         );
  268. isa_ok( $statements->[1], 'PPI::Statement::Include',    'Statement 2: isa Include'            );
  269. ok( $statements->[1]->specialized,                      'Statement 2: is specialized'         );
  270. isa_ok( $statements->[2], 'PPI::Statement::Null',       'Statement 3: isa Null'               );
  271. ok( $statements->[2]->specialized,                      'Statement 3: is specialized'         );
  272. isa_ok( $statements->[3], 'PPI::Statement::Compound',   'Statement 4: isa Compound'           );
  273. ok( $statements->[3]->specialized,                      'Statement 4: is specialized'         );
  274. isa_ok( $statements->[4], 'PPI::Statement::Expression', 'Statement 5: isa Expression'         );
  275. ok( $statements->[4]->specialized,                      'Statement 5: is specialized'         );
  276. isa_ok( $statements->[5], 'PPI::Statement::Break',      'Statement 6: isa Break'              );
  277. ok( $statements->[5]->specialized,                      'Statement 6: is specialized'         );
  278. isa_ok( $statements->[6], 'PPI::Statement::Scheduled',  'Statement 7: isa Scheduled'          );
  279. ok( $statements->[6]->specialized,                      'Statement 7: is specialized'         );
  280. isa_ok( $statements->[7], 'PPI::Statement::Sub',        'Statement 8: isa Sub'                );
  281. ok( $statements->[7]->specialized,                      'Statement 8: is specialized'         );
  282. isa_ok( $statements->[8], 'PPI::Statement::Variable',   'Statement 9: isa Variable'           );
  283. ok( $statements->[8]->specialized,                      'Statement 9: is specialized'         );
  284. is( ref $statements->[9], 'PPI::Statement',             'Statement 10: is a simple Statement' );
  285. ok( ! $statements->[9]->specialized,                    'Statement 10: is not specialized'    );
  286.  
  287. =end testing
  288.  
  289. =cut
  290.  
  291. # Yes, this is doing precisely what it's intending to prevent
  292. # client code from doing.  However, since it's here, if the
  293. # implementation changes, code outside PPI doesn't care.
  294. sub specialized {
  295.     __PACKAGE__ ne ref $_[0];
  296. }
  297.  
  298. =pod
  299.  
  300. =head2 stable
  301.  
  302. Much like the L<PPI::Document> method of the same name, the ->stable
  303. method converts a statement to source and back again, to determine if
  304. a modified statement is still legal, and won't be interpreted in a
  305. different way.
  306.  
  307. Returns true if the statement is stable, false if not, or C<undef> on
  308. error.
  309.  
  310. =cut
  311.  
  312. sub stable {
  313.     die "The ->stable method has not yet been implemented";    
  314. }
  315.  
  316.  
  317.  
  318.  
  319.  
  320. #####################################################################
  321. # PPI::Element Methods
  322.  
  323. # Is the statement complete.
  324. # By default for a statement, we need a semi-colon at the end.
  325. sub _complete {
  326.     my $self = shift;
  327.     my $semi = $self->schild(-1);
  328.     return !! (
  329.         defined $semi
  330.         and
  331.         $semi->isa('PPI::Token::Structure')
  332.         and
  333.         $semi->content eq ';'
  334.     );
  335. }
  336.  
  337. # You can insert either a statement or a non-significant token.
  338. sub insert_before {
  339.     my $self    = shift;
  340.     my $Element = _INSTANCE(shift, 'PPI::Element') or return undef;
  341.     if ( $Element->isa('PPI::Statement') ) {
  342.         return $self->__insert_before($Element);
  343.     } elsif ( $Element->isa('PPI::Token') and ! $Element->significant ) {
  344.         return $self->__insert_before($Element);
  345.     }
  346.     '';
  347. }
  348.  
  349. # As above, you can insert a statement, or a non-significant token
  350. sub insert_after {
  351.     my $self    = shift;
  352.     my $Element = _INSTANCE(shift, 'PPI::Element') or return undef;
  353.     if ( $Element->isa('PPI::Statement') ) {
  354.         return $self->__insert_after($Element);
  355.     } elsif ( $Element->isa('PPI::Token') and ! $Element->significant ) {
  356.         return $self->__insert_after($Element);
  357.     }
  358.     '';
  359. }
  360.  
  361. 1;
  362.  
  363. =pod
  364.  
  365. =head1 TO DO
  366.  
  367. - Complete, freeze and document the remaining classes
  368.  
  369. =head1 SUPPORT
  370.  
  371. See the L<support section|PPI/SUPPORT> in the main module.
  372.  
  373. =head1 AUTHOR
  374.  
  375. Adam Kennedy E<lt>adamk@cpan.orgE<gt>
  376.  
  377. =head1 COPYRIGHT
  378.  
  379. Copyright 2001 - 2010 Adam Kennedy.
  380.  
  381. This program is free software; you can redistribute
  382. it and/or modify it under the same terms as Perl itself.
  383.  
  384. The full text of the license can be found in the
  385. LICENSE file included with this module.
  386.  
  387. =cut
  388.